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Foreword 



This Technical Specification has been produced by the 3' Generation Partnership Project (3GPP). 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 
where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 

Introduction 

The present document is part 5 of a multi-part TS covering the 3"* Generation Partnership Project: Technical 
Specification Group Core Network; Open Service Access (OSA); Application Programming Interface (API), as 
identified below. The API specification (3GPP TS 29.198) is structured in the following Parts: 

Part 1: Overview 

Part 2: Common Data Definitions 

Part 3: Framework 

Part 4: Call Control SCF 

Part 5: User Interaction SCF 

Part 6: MobiUty SCF 

Part 7: Terminal Capabilities SCF 

Part 8: Data Session Control SCF 

Part 9: Generic Messaging SCF 

Part 10: Connectivity Manager SCF 

Part 1 1 : Account Management SCF 

Part 12: Charging SCF 

The Mapping specification of the OSA APIs and network protocols (3GPP TR 29.998) is also structured as above. 
A mapping to network protocols is however not applicable for all Parts, but the numbering of Parts is kept. 
Also in case a Part is not supported in a Release, the numbering of the parts is maintained. 



(not part of 3GPP Release 4) 
(not part of 3GPP Release 4) 



1^ OSA API specifications 29.198-fainily 


^^^ OSA API Mapping - 29.998-familv ^^^^^Hl 


29.198-1 


Part 1: Overview 


29.998-1 


Part 1: Overview 


29.198-2 


Part 2: Common Data Definitions 


29.998-2 


Not Applicable 


29.198-3 


Part 3: Framework 


29.998-3 


Not Applicable 


29.198-4 


Part 4: Call Control SCF 


29.998-4-1 


Subpart 1: Generic Call Control - CAP mapping 


29.998-4-2 




29.198-5 


Part 5: User Interaction SCF 


29.998-5-1 


Subpart 1: User Interaction - CAP mapping 


29.998-5-2 




29.998-5-3 




29.998-5-4 


Subpart 4: User Interaction - SMS mapping 


29.198-6 


Part 6: Mobility SCF 


29.998-6 


User Status and User Location - MAP mapping 


29.198-7 


Part 7: Terminal Capabilities SCF 


29.998-7 


Not Applicable 


29.198-8 


Part 8: Data Session Control SCF 


29.998-8 


Data Session Control - CAP mapping 


29.198-9 


Part 9: Generic Messaging SCF 


29.998-9 


Not Applicable 


29.198-10 


Part 10: Connectivity Manager SCF 


29.998-10 


Not Applicable 


29.198-11 


Part 11: Account Management SCF 


29.998-11 


Not Applicable 


29.198-12 


Part 12: Charging SCF 


29.998-12 


Not Applicable 
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Scope 



This document is Part 5 of the Stage 3 specification for an Apphcation Programming Interface (API) for Open Service 
Access (OSA). 

The OSA specifications define an architecture that enables application developers to make use of network functionality 
through an open standardised interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA 
are contained in 3GPP TS 23.127 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the User Interaction (UI) Service Capability Feature (SCF) aspects of the interface. All 
aspects of the User Interaction SCF are defined here, these being: 

Sequence Diagrams 

Class Diagrams 

Interface specification plus detailed method descriptions 

State Transition diagrams 

Data definitions 

IDL Description of the interfaces 

The process by which this task is accomplished is through the use of object modelling techniques described by the 
Unified Modelling Language (UML). 

This specification has been defined jointly between 3GPP TSG CN WG5, ETSI SPAN 12 and the Parlay Consortium, 
in co-operation with the JAIN consortium. 



References 



The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TS 29.198-1: "Open Service Access; Application Programming Interface; Part 1: 

Overview". 

[2] 3GPP TS 22.127: "Stage 1 Service Requirement for the Open Service Access (OSA) (Release 4)". 

[3] 3GPP TS 23.127: "Virtual Home Environment (Release 4)". 



3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the terms and definitions given in TS 29.198-1 [1] apply. 
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3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in TS 29.198-1 [1] apply. 

4 Generic and Call User Interaction SCF 

The Generic User Interaction (GUI) Service Capability Feature (SCF) is used by applications to interact with end users. 
It consists of two interfaces: 

1) User Interaction Manager (UIM), containing management functions for User Interaction related issues; 

2) Generic User Interaction (GUI), containing methods to interact with an end-user. 

The GUI SCF is described in terms of the methods in the Generic User Interaction (GUI) interfaces. 
The following table gives an overview of the GUI methods and to which interfaces these methods belong. 

Table 1 : Overview of GUI interfaces and their methods 



V User Interaction Manaqer (UIM) ^^^m. 


Generic User Interaction (GUI) ~B 


^^11 


createUI 


sendlnfoReq 


createUICall 


sendlnfoRes 


createNotification 


sendlnfoErr 


destroyUINotification 


sendlnfoAndCollectReq 


reportNotification 


sendlnfoAndCollectRes 


userlnteractionAborted 


sendlnfoAndCollectErr 


userlnteractionNotificationlnterrupted 


release 


userlnteractionNotificationContinued 


UserlnteractionFaultDetected 


changeNotification 




getNotification 





The following table gives an overview of the Call User Interaction methods and to which interfaces these methods 
belong. 

Table 2: Overview of Call User Interaction interfaces and their methods 



Hji. — User Interaction Manager (UIM) 


Call User Interaction 


■1 


As defined for the Generic User Interaction SCF 


Inherits from Generic User Interaction and adds: 


recordlVlessageReq 


recordMessageRes 


recordMessageErr 


deletelVlessageReq 


deletelVlessageRes 


deleteMessageErr 


abortActionReq 


abortActionRes 


abortActionErr 



The IpUI Interface provides functions to send information to, or gather information from the user, i.e. this interface 
allows applications to send SMS and USSD messages. An application can use this interface independently of other 
SCFs. The IpUICall Interface provides functions to send information to, or gather information from the user (or call 
party) attached to a call. 

The following clauses describe each aspect of the GUI Service Capability Feature (SCF). 

The order is as follows: 

• the Sequence diagrams give the reader a practical idea of how each of the SCF is implemented; 

• the Class relationships clause shows how each of the interfaces applicable to the SCF, relate to one another; 
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• the Interface specification clause describes in detail each of the interfaces shown within the Class diagram part. 
This clause also includes Call User Interaction; 

• the State Transition Diagrams (STD) show the progression of internal processes either in the application, or 

Gateway; 

• the Data definitions clause shows a detailed expansion of each of the data types associated with the methods 
within the classes. Note that some data types are used in other methods and classes and are therefore defined 
within the Common Data types part of this specification (29.198-2). 
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Sequence Diagrams 



5.1 Alarm Call 

The following sequence diagram shows a 'reminder message', in the form of an alarm, being delivered to a customer as 
a result of a trigger from an application. Typically, the application would be set to trigger at a certain time, however, the 
application could also trigger on events. 



:(Loaical 
View::lp... 


: IpADDCall 



IpAppUICall IpCallControlManaqer 



: IpCall 



1: new() 



-^ 



: createCall( 



6: 'forward even] 



f^ 



r 



11: 'forWard event' 



[f- 



-^ 



3: new() 



4: routeReq{ ) 



-^D 



->^ 



5: routeRes{ ) 



createUICallO 



sendlnfoReq{ ) 



^ 



10: sendlnfoRes( ) 



12:'release( ) 



13: release( ) 



->, 



IpAppUIManaqer 



: IpUICall 



-^ 



: new() 



^ 



-^ 



-^ 



1: This message is used to create an object implementing the IpAppCall interface. 

2: This message requests the object implementing the IpCallControlManager interface to create an object 
implementing the IpCall interface. 

3: Assuming that the criteria for creating an object implementing the IpCall interface (e.g. load control values not 
exceeded) is met it is created. 
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4: This message instructs the object implementing the IpCall interface to route the call to the customer destined to 
receive the 'reminder message'. 

5: This message passes the result of the call being answered to its callback object. 

6: This message is used to forward the previous message to the IpAppLogic. 

7: The application requests a new UlCall object that is associated with the call object. 

8: Assuming all criteria are met, a new UlCall object is created by the service. 

9: This message instructs the object implementing the IpUICall interface to send the alarm to the customer's call. 

10: When the announcement ends this is reported to the call back interface. 

1 1 : The event is forwarded to the application logic. 

12: The application releases the UlCall object, since no further announcements are required. Alternatively, the 
application could have indicated P_FINAL_R£QUEST in the sendlnfoReq in which case the UlCall object would have 
been implicitly released after the announcement was played. 

13: The application releases the call and all associated parties. 



Call Barring 1 



The following sequence diagram shows a call barring service, initiated as a result of a prearranged event being received 
by the framework. Before the call is routed to the destination number, the calling party is asked for a PIN code. 
The code is accepted and the call is routed to the original called party. 
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: (Logical 

View::lp... IpAppCallControl Manager 



: IpAppCall X J_ : IpCall x : IpUICall 

IpAppUICall IpCallControlManaqer IpUIManaqer 




1: This message is used by the application to create an object implementing the IpAppCallControlManager interface. 

2: This message is sent by the application to enable notifications on new call events. As this sequence diagram depicts 
a call barring service, it is likely that all new call events destined for a particular address or address range prompted for 
a password before the call is allowed to progress. When a new call, that matches the event criteria set, arrives, a 
message (not shown) is directed to the object implementing the IpCallControlManager. Assuming that the criteria for 
creating an object implementing the IpCall interface (e.g. load control values not exceeded) is met, other messages (not 
shown) are used to create the call and associated call leg object. 

3: This message is used to pass the new call event to the object implementing the IpAppCallControlManager interface. 

4: This message is used to forward the previous message to the IpAppLogic. 

5: This message is used by the application to create an object implementing the IpAppCall interface. The reference to 
this object is passed back to the object implementing the IpCallControlManager using the return parameter of the 
callEventNotify. 

6: This message is used to create a new UlCall object. The reference to the call object is given when creating the 
UlCall. 

7: Provided all the criteria are fulfilled, a new UlCall object is created. 

8: The call barring service dialogue is invoked. 
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9: The result of the dialogue, which in this case is the PIN code, is returned to its callback object. 

10: This message is used to forward the previous message to the IpAppLogic. 

1 1 : This message releases the UlCall object. 

12: Assuming the correct PIN is entered, the call is forward routed to the destination party. 

13: This message passes the result of the call being answered to its callback object. 

14: This message is used to forward the previous message to the IpAppLogic 

15: When the call is terminated in the network, the application will receive a notification. This notification will always 
be received when the call is terminated by the network in a normal way, the application does not have to request this 
event explicitly. 

16: The event is forwarded to the application. 

17: The application shall free the call related resources in the gateway by calling deassignCall. 



5.3 Prepaid 



This sequence shows a Pre-Paid Application (PPA). The subscriber is using a pre-paid card or credit card to pay for the 
call. The application each time allows a certain timeslice for the call. After the timeslice, a new timeslice can be started 
or the application can terminate the call. In the following sequence the end-user will received an announcement before 
his final timeslice. 
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Prepaid : : IpAppCall 

(Logical View:... 

:inew() 



: ipAppUiCaii 



: ipCaii 



IpAppCaiiControilVlanaqer 

>n I 

U 2:enableOallNotification( i) 



(f- 



4: "fon«/ard event" 



f^ 



3:ca|IEventNotify( )| 



(f- 



5: new() 



6: supervi^eCallReq( 



7:roL)teReq( 



-^ 



-^ 



9: "forward ever|t^ 

[f 



8:s'uperviseCallRes( 



10:superviseCallReq( ) 



1 ^: "forward eveii^ 



11:si^perviseCallRes( 



-^ 



13:supervi4eCallReq( ) 

14: ^uperviseCallRes( 



-^ 



15: "forward evefff 

(r — 



[T 



16:createUilCall 



: IpU I Manager 



I pC al I Cont rol Man ager 



: IpUICall 



-^ 



17:sendlnfoReq( ) 



19: "forward event" 



18:sendlnfoRes( ) 



^0: release( ) 



"0 



-^D 



21 :superviseCallReq( 



^ 



23: "fonn/ard event: 22: ?uperviseCallRes( 



(T 



24: rele9se( ) 



-^ 



1: This message is used by the application to create an object implementing the IpAppGenericCallControlManager 
interface. 
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2: This message is sent by the application to enable notifications on new call events. As this sequence diagram depicts 
a pre-paid service, it is likely that only new call events within a certain address range will be enabled. When a new call, 
that matches the event criteria, arrives a message (not shown) is directed to the object implementing the 
IpCallControlManager. Assuming that the criteria for creating an object implementing the IpCall interface (e.g. load 
control values not exceeded) is met, other messages (not shown) are used to create the call and associated call leg 
object. 

3: The incoming call triggers the Pre-Paid Application (PPA). 

4: The message is forwarded to the application. 

5: A new object on the application side for the Generic Call object is created 

6: The PPA requests to supervise the call. The application will be informed after the period indicated in the message. 
This period is related to the credits left on the account of the pre-paid subscriber. 

7: Before continuation of the call, PPA sends all charging information, a possible tariff switch time and the call 
duration supervision period, towards the GW which forwards it to the network. 

8: At the end of each supervision period the application is informed and a new period is started. 

9: The message is forwarded to the application. 

10: The PPA requests to supervise the call for another call duration. 

1 1 : At the end of each supervision period the application is informed and a new period is started. 

12: The message is forwarded to the application. 

13: The PPA requests to supervise the call for another call duration. 

14: When the user is almost out of credit an announcement is played to inform about this. The announcement is played 
only to the leg of the A-party, the B-party will not hear the announcement. 

15: The message is forwarded to the application. 

16: A new UlCall object is created and associated with the controlling leg. 

17: An announcement is played to the controlling leg informing the user about the near-expiration of his credit limit. 
The B-subscriber will not hear the announcement. 

18: When the announcement is completed the application is informed. 

19: The message is forwarded to the application. 

20: The application releases the UlCall object. 

21: The user does not terminate so the application terminates the call after the next supervision period. 

22: The supervision period ends. 

23: The event is forwarded to the logic. 

24: The application terminates the call. Since the User Interaction is already explicitly terminated no 
userlnteractionFaultDetected is sent to the application. 



5.4 Pre-Paid with Advice of Charge (AoC) 

This sequence shows a Pre-Paid Application (PPA) that uses the Advice of Charge (AoC) feature. The application will 
send the charging information before the actual call setup and when during the call the charging changes new 
information is sent in order to update the end-user. 

NOTE: the AoC feature requires an application in the end-user terminal to display the charges for the call, 
depending on the information received from the application. 
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Prepaid : ji 

(Logical Vie... IpAppCallControl Manager 



: IpAppCall 



:lpAppUICall 



pCallControlManager 
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r 
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1: This message is used by the application to create an object implementing the IpAppCallControlManager interface. 

2: This message is sent by the application to enable notifications on new call events. As this sequence diagram depicts 
a pre-paid service, it is likely that only new call events within a certain address range will be enabled. When a new call, 
that matches the event criteria, arrives a message (not shown) is directed to the object implementing the 
IpCallControlManager. Assuming that the criteria for creating an object implementing the IpCall interface (e.g. load 
control values not exceeded) is met, other messages (not shown) are used to create the call and associated call leg 
object. 

3: The incoming call triggers the Pre-Paid Application (PPA). 

4: The message is forwarded to the application. 

5: A new object on the application side for the Call object is created 

6: The PPA sends the AoC information (e.g. the tariff switch time), (it shall be noted the PPA contains ALL the tariff 
information and knows how to charge the user). 

During this call sequence 2 tariff changes take place. The call starts with tariff 1, and at the tariff switch time (e.g. 18:00 
hours) switches to tariff 2. The application is not informed about this (but the end-user is!) 

7: The PPA requests to supervise the call. The application will be informed after the period indicated in the message. 
This period is related to the credits left on the account of the pre-paid subscriber. 

8: The application requests to route the call to the destination address. 

9: At the end of each supervision period the application is informed and a new period is started. 

10: The message is forwarded to the application. 

1 1 : The PPPA requests to supervise the call for another call duration. 

12: At the end of each supervision period the application is informed and a new period is started. 

13: The message is forwarded to the application. 

14: Before the next tariff switch (e.g. 19:00 hours) the application sends a new AOC with the tariff switch time. Again, 
at the tariff switch time, the network will send AoC information to the end-user. 

15: The PPA requests to supervise the call for another call duration. 

16: When the user is almost out of credit an announcement is played to inform about this (19-21). The announcement is 
played only to the leg of the A-party, the B-party will not hear the announcement. 

17: The message is forwarded to the application. 

18: The application creates a new call back interface for the User Interaction messages. 

19: A new UI Call object that will handle playing of the announcement needs to be created 

20: The Gateway creates a new UI call object that will handle playing of the announcement. 

21: With this message the announcement is played to the calling party. 

22: The user indicates that the call should continue. 

23: The message is forwarded to the application. 

24: The user does not terminate so the application terminates the call after the next supervision period. 

25: The user is out of credit and the application is informed. 

26: The message is forwarded to the application. 

27: With this message the application requests to release the call. 

28: Terminating the call which has still a UlCall object associated will result in a userlnteractionFaultDetected. 

The UlCall object is terminated in the gateway and no further communication is possible between the UlCall and the 

application. 
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Class Diagrams 



The application Generic User Interaction Service (GUIS) package consists of one IpAppUIManager interface, zero or 
more IpAppUI interfaces and zero or more IpAppUICall interfaces. 

The GUIS package consists of one IpUIManager interface, zero or more IpUI interfaces and zero or more IpUICall 
interfaces. 

The class diagram in the following figure shows the interfaces that make up the application GUIS package and the 
GUIS package. Communication between these packages is done via the «uses» relationships. 

The IpUICall implements call related User Interaction and it inherits from the non call related IpUI interface. The same 
holds for the corresponding application interfaces. 
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«lnterface» 
Iplnterface 



«lnterface» 
IpAppUIManager 

userlnteractionAbortedO 
reportNotificationO 

userlnteractionNotificationlnterruptedO 
userlnteractionNotificationContinuedO 



«lnterface» 
IpUIManager 

createUlO 

oreateUICallO 

createNotificationO 

destroyNotificationO 

changeNotificationO 

getNotificationO 



«lnterface» 
IpAppUl 



send Info Re s() 

sendlnfoErr() 

sendlnfoAndCollectResO 

sendlnfoAndCollectErrO 

usetinteractionFaultDetectedO 



«lntei1ace» 
IpUl 



sendlnfoReqO 

sendlnfoAndCollectReqO 

releaseO 



«lnterface» 
IpAppUICall 



recordMessageResO 
_ recordMessageErrO 
deleteMessageResO 
deleteMessageErrO 
abortActionResO 
abortActionErrO 



«lnterface» 
IpUICall 



recordMessageReqO 
deleteMessageReqO 
abortActionReqO 



«lnterface» 
IpService 

setCallbackO 
setCallbackWithSessionlDO 



Figure: Generic User Interaction Package Overview 



7 The Service Interface Specifications 

7.1 Interface Specification Format 

This clause defines the interfaces, methods and parameters that form a part of the API specification. The Unified 
Modelhng Language (UML) is used to specify the interface classes. The general format of an interface specification is 
described below. 



7.1.1 



Interface Class 



This shows a UML interface class description of the methods supported by that interface, and the relevant parameters 
and types. The Service and Framework interfaces for enterprise-based client applications are denoted by classes with 
name Ip<name>. The callback interfaces to the applications are denoted by classes with name IpApp<name>. For 
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the interfaces between a Service and the Framework, the Service interfaces are typically denoted by classes with name 
IpSvc<name>, while the Framework interfaces are denoted by classes with name IpFw<name>. 

7. 1 .2 Method descriptions 

Each method (API method "call") is described. All methods in the API return a value of type TpResult, indicating, 
amongst other things, if the method invocation was sucessfully executed or not. 

Both synchronous and asynchronous methods are used in the API. Asynchronous methods are identified by a 'Req' 
suffix for a method request, and, if applicable, are served by asynchronous methods identified by either a 'Res' or 'Err' 
suffix for method results and errors, respectively. To handle responses and reports, the application or service developer 
shall implement the relevant IpApp<name> or IpSvc<name> interfaces to provide the callback mechanism. 

7. 1 .3 Parameter descriptions 

Each method parameter and its possible values are described. Parameters described as 'in' represent those that shall have 
a value when the method is called. Those described as 'out' are those that contain the return result of the method when 
the method returns. 

7.1.4 State Model 

If relevant, a state model is shown to illustrate the states of the objects that implement the described interface. 

7.2 Base Interface 

7.2.1 Interface Class Iplnterface 

All application, framework and service interfaces inherit from the following interface. This API Base Interface does not 
provide any additional methods. 



«lnterface» 
Iplnterface 



7.3 Service Interfaces 
7.3.1 Overview 

The Service Interfaces provide the interfaces into the capabilities of the underlying network - such as call control. User 
Interaction, messaging, mobility and connectivity management. 

The interfaces that are implemented by the services are denoted as 'Service Interface'. The corresponding interfaces that 
shall be implemented by the application (e.g. for API callbacks) are denoted as 'Application Interface'. 

7.4 Generic Service Interface 
7.4.1 Interface Class IpService 

Inherits from: Iplnterface 

All service interfaces inherit from the following interface. 
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«lnterface» 
IpService 



setCallback (applnterface : in IplnterfaceRef) : TpResult 

setCallbackWithSessionID (applnterface : in IplnterfaceRef, sessionID : in TpSessionID) : TpResult 



Method 
setCallback () 

This method specifies the reference address of the callback interface that a service uses to invoke methods on the 
application. 

Parameters 

applnterface : in IplnterfaceRef 

Specifies a reference to the application interface, which is used for callbacks. 

Raises 
TpGeneralException 



Method 
SetCallbackWithSessionID () 

This method specifies the reference address of the application's callback interface that a service uses for interactions 
associated with a specific session ID: e.g. a specific call, or call leg. 

Parameters 

applnterface : in IplnterfaceRef 

Specifies a reference to the application interface, which is used for callbacks. 

sessionID : in TpSessionID 

Specifies the session for which the service can invoke the application's callback interface. 

Raises 
TpGeneralException 
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8 Generic User Interaction Interface Classes 

The Generic User Interaction Service (GUIS) interface is used by applications to interact with end users. The GUIS is 
represented by the IpUIManager, IpUI and IpUICall interfaces that interface to services provided by the network. To 
handle responses and reports, the developer shall implement IpAppUIManager and IpAppUI interfaces to provide the 
callback mechanism. 

8.1 Interface Class IpUIManager 

Inherits from: IpService. 

This interface is the 'service manager' interface for the GUIS and provides the management functions to the GUIS. 



«lnterface» 
IpUIManager 



createUI (appUl : in IpAppUIRef, userAddress : in TpAddress, userlnteraction : out TpUlldentifierRef) : 
TpResult 

createUICall (appUl : in IpAppUICallRef, uiTargetObject : in TpUITargetObject, userlnteraction : out 
TpUICallldentifierRef) : TpResult 

createNotification (appUIManager : in IpAppUIManagerRef, eventCriteria : in TpUIEventCriteria, 
assignmentID : out TpAssignmentlDRef) : TpResult 

destroyNotification (assignmentID : in TpAssignmentID) : TpResult 

changeNotification (assignmentID : in TpAssignmentID, evenCriteria : in TpUIEventCriteria) : TpResult 

getNotification (eventCriteria : out TpUIEventCriteriaResultSetRef) : TpResult 



Method 
createUI () 

This method is used to create a new User Interaction object for non-call related purposes. 

Parameters 

appUI : in IpAppUIRef 

Specifies the application interface for callbacks from the User Interaction created. 

userAddress : in TpAddress 

Indicates the end-user with whom to interact. 

userlnteraction : out TpUlldentifierRef 

Specifies the interface and sessionID of the User Interaction created. 

Raises 

TpGUISException, TpGeneralException 
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Method 
createUICallO 

This method is used to create a new User Interaction object for call related purposes. 

The User Interaction can take place to the specified party or to all parties in a call. Note that for certain implementation 
User Interaction can only be performed towards the controlling call party, which shall be the only party in the call. 

Parameters 

appUI : in IpAppUICallRef 

Specifies the application interface for callbacks from the User Interaction created. 

uiTargetObject : in TpUITargetObject 

Specifies the object on which to perform the User Interaction. This can either be a Call, Multi-Party Call or call leg 
object. 

userlnteraction : out TpUICallldentifierRef 

Specifies the interface and sessionID of the User Interaction created. 

Raises 

TpGUISException, TpGeneralException 



Method 

createNotif ication () 

This method is used by the application to install specified notification criteria, for which the reporting is implicitly 
activated. If some application already requested notifications with criteria that overlap the specified criteria, the request 
is refused with P_GUIS_INVALID_CRITERIA. 

The criteria are said to overlap if both originating and terminating ranges overlap and the same number plan is used and 
the same servicecode is used. 

If the same application requests two notifications with exactly the same criteria but different callback references, the 
second callback will be treated as an additional callback. This means that the callback will only be used in case when 
the first callback specified by the application is unable to handle the reportNotification (e.g. due to overload or failure). 

Parameters 

appUIManager : in IpAppUIManagerRef 

If this parameter is set (i.e. not NULL) it specifies a reference to the application interface, which is used for callbacks. If 
set to NULL, the application interface defaults to the interface specified via the setCallback() method. 

eventCriteria : in TpUIEventCriteria 

Specifies the event specific criteria used by the application to define the event required, like user address and service 
code. 

assignmentID : out TpAssignmentlDRef 

Specifies the ID assigned by the generic User Interaction manager interface for this newly installed notification criteria. 
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Raises 

TpGUISException, TpGeneralException 



Method 

destroyNotif ication ( ) 

This method is used by the application to destroy previously installed notification criteria via the createNotification 
method. 

Parameters 

assignmentID : in TpAssignmentID 

Specifies the assignment ID given by the generic User Interaction manager interface when the previous 
createNotificationO was called. If the assignment ID does not correspond to one of the valid assignment IDs, the 
framework will return the error code P_INVALID_ASSIGNMENTID. 

Raises 

TpGUISException, TpGeneralException 



Method 

changeNotif ication ( ) 

This method is used by the application to change the event criteria introduced with createNotification method. Any 
stored notification request associated with the specified assignementID will be replaced with the specified events 
requested. 

Parameters 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the manager interface for the event notification. 

evenCriteria : in TpUIEventCriteria 

Specifies the new set of event criteria used by the application to define the event required. Only events that meet these 
criteria are reported. 

Raises 

TpGUISException, TpGeneralException 



Method 

getNot if ication () 

This method is used by the application to query the event criteria set with createNotification or changeNotification. 

Parameters 

eventCriteria : out TpUIEventCriteriaResultSetRef 

Specifies the event specific criteria used by the application to define the event required. Only events that meet these 
criteria are reported. 
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Raises 

TpGUISException, TpGeneralException 

8.2 Interface Class IpAppUIManager 

Inherits from: Iplnterface. 

The GUIS manager application interface provides the application callback functions to the GUIS. 



«lnterface» 
IpAppUIManager 



userlnteractionAborted (userlnteraction : in TpUlldentifier) : TpResult 

reportNotification (userlnteraction : in TpUlldentifier, eventlnfo : in TpUIEventlnfo, assignmentID : in 
TpAssignmentID, appUl : out IpAppUIRefRef) : TpResult 

userlnteractionNotificationlnterrupted () : TpResult 

userlnteractionNotificationContinued () : TpResult 



Method 
userlnteractionAborted ( ) 

This method indicates to the application that the User Interaction service instance has terminated or closed abnormally. 
No further communication will be possible between the User Interaction service instance and application. 

Parameters 

userlnteraction : in TpUlldentifier 

Specifies the interface and sessionID of the User Interaction service that has terminated. 

Raises 

TpGUISException, TpGeneralException 



Method 
reportNotification ( ) 

This method notifies the application of an occured network event which matches the criteria installed by the 
createNotification method. 

Parameters 

userlnteraction : in TpUlldentifier 

Specifies the reference to the interface and the sessionID to which the notification relates. 

eventlnfo : in TpUIEventlnfo 

Specifies data associated with this event. 
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assignmentID : in TpAssignmentID 

Specifies the assignment id which was returned by the createNotification() method. The application can use assignment 
id to associate events with event specific criteria and to act accordingly. 

appUI : out IpAppUIRefRef 

Specifies a reference to the appUcation interface, which implements the callback interface for the new User Interaction. 

Raises 

TpGUISException, TpGeneralException 



Method 

userlnteractionNotif icationlnterrupted ( ) 

This method indicates to the application that all event notifications have been temporary interrupted (for example, due 
to faults detected). Note that more permanent failures are reported via the Framework (integrity management). 

Parameters 

No Parameters were identified for this method 

Raises 

TpGUISException, TpGeneralException 



Method 

userlnteractionNotif icationContinued ( ) 

This method indicates to the application that event notifications wiU again be possible. 

Parameters 

No Parameters were identified for this method 

Raises 

TpGUISException, TpGeneralException 



8.3 Interface Class IpUl 

Inherits from: IpService. 

The User Interaction Service Interface provides functions to send information to, or gather information from the user. 
An application can use the User Interaction Service Interface independently of other services. 



«lnterface» 
IpUl 



sendlnfoReq (userlnteractionSessionID : in TpSessionID, info : in TpUllnfo, language : in TpLanguage, 
variablelnfo : in TpUIVariablelnfoSet, repeatlndicator : in Tplnt32, responseRequested : in 
TpUIResponseRequest, assignmentID : out TpAssignmentlDRef) : TpResult 

sendlnfoAndCollectReq (userlnteractionSessionID : in TpSessionID, info : in TpUllnfo, language : in 
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TpLanguage, variablelnfo : in TpUIVariablelnfoSet, criteria : in TpUICollectCriteria, responseRequested : 
in TpUIResponseRequest, assignmentID : out TpAssignmentlDRef) : TpResult 

release (userlnteractionSessionID : in TpSessionID) : TpResult 



Method 
sendinf oReq ( ) 

This asynchronous method plays an announcement or sends other information to the user. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User hiteraction session ID of the User Interaction. 

info : in TpUIInfo 

Specifies the information to send to the user. This information can be: 

- an infoID, identifying pre-defined information to be send (announcement and/or text); 

- a string, defining the text to be sent; 

- a URL , identifying pre-defined information or data to be sent to or downloaded into the terminal. 

language : in TpLanguage 

Specifies the Language of the information to be send to the user. 

variablelnfo : in TpUIVariablelnfoSet 

Defines the variable part of the information to send to the user. 

repeat Indicator : in Tplnt32 

Defines how many times the information shall be sent to the end-user. A value of zero (0) indicates that the 
announcement shall be repeated until the call or call leg is released or an abortActionReqO is sent. 

responseRequested : in TpUIResponseRequest 

Specifies if a response is required from the call User Interaction service, and any action the service should take. 

assignmentID : out TpAssignmentlDRef 

Specifies the ID assigned by the generic User Interaction interface for a User Interaction request. 

Raises 

TpGUISException, TpGeneralException 



Method 

sendinf oAndCollectReq ( ) 

This asynchronous method plays an announcement or sends other information to the user and collects some information 
from the user. The announcement usually prompts for a number of characters (for example, these are digits or text 
strings such as "YES" if the user's terminal device is a phone). 
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Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

info : in TpUIInfo 

Specifies the ID of the information to send to the user. This information can be: 

- an infoID, identifying pre-defined information to be send (announcement and/or text); 

- a string, defining the text to be sent; 

- a URL , identifying pre-defined information or data to be sent to or downloaded into the terminal. 

language : in TpLanguage 

Specifies the Language of the information to be send to the user. 

variablelnfo : in TpUIVariablelnfoSet 

Defines the variable part of the information to send to the user. 

criteria : in TpUICollectCriteria 

Specifies additional properties for the collection of information, such as the maximum and minimum number of 
characters, end character, first character timeout and inter-character timeout. 

responseRequested : in TpUIResponseRequest 

Specifies if a response is required from the call User Interaction service, and any action the service should take. For this 
case it can especially be used to indicate e.g. the final request. 

assignmentID : out TpAssignmentlDRef 

Specifies the ID assigned by the generic User Interaction interface for a User Interaction request. 

Raises 

TpGUISException, TpGeneralException 



Method 
release () 

This method requests that the relationship between the application and the User Interaction object be released. It causes 
the release of the used User Interaction resources and interrupts any ongoing User Interaction. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction created. 

Raises 

TpGUISException, TpGeneralException 



8.4 Interface Class IpAppUl 

Inherits from: Iplnterface. 
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The User Interaction Application Interface is implemented by the client application developer and is used to handle 
generic User Interaction request responses and reports. 



«lnterface» 
IpAppUl 



sendlnfoRes (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, response : in 
TpUIReport) : TpResult 

sendlnfoErr (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, error : in 
TpUIError) : TpResult 

sendlnfoAndCollectRes (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, 
response : in TpUIReport, collectedlnfo : in TpString) : TpResult 

sendlnfoAndCollectErr (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, 
error : in TpUIError) : TpResult 

userlnteractionFaultDetected (userlnteractionSessionID : in TpSessionID, fault : in TpUIFault) : TpResult 



Method 
sendlnfoRes ( ) 

This asynchronous method informs the application about the start or the completion of a sendInfoCallReq(). This 
response is called only if the responseRequested parameter of the sendlnfoCallReqO method was set to 
P_UICALL_RESPONSE_REQUIRED. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the generic User Interaction interface for a User Interaction request. 

response : in TpUIReport 

Specifies the type of response received from the user. 

Raises 

TpGUISException, TpGeneralException 



Method 
sendlnfoErr ( ) 

This asynchronous method indicates that the request to send information was unsuccessful. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 
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assignmentID : in TpAssignmentID 

Specifies the ID assigned by the GUI interface for a User Interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 

Raises 

TpGUISException, TpGeneralException 

Method 
sendlnfoAndCollectRes () 

This asynchronous method returns the information collected to the application. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the GUI interface for a User Interaction request. 

response : in TpUIReport 

Specifies the type of response received from the user. 

collectedlnfo : in TpString 

Specifies the information collected from the user. 

Raises 

TpGUISException, TpGeneralException 



Method 
sendlnfoAndCollectErr () 

This asynchronous method indicates that the request to send information and collect a response was unsuccessful. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the GUI interface for a User Interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 

Raises 

TpGUISException, TpGeneralException 
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Method 
userlnteractionFaultDetected ( ) 

This method indicates to the application that a fault has been detected in the User Interaction. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the interface and sessionID of the User Interaction service in which the fault has been detected. 

fault : in TpUIFault 

Specifies the fault that has been detected. 

Raises 

TpGUISException, TpGeneralException 



8.5 Interface Class IpUICall 

Inherits from: IpUI. 

The Call User Interaction Service Interface provides functions to send information to, or gather information from the 
user (or call party) to which a call leg is connected. An application can use the Call User Interaction Service Interface 
only in conjunction with another service interface, which provides mechanisms to connect a call leg to a user. At 
present, only the Call Control service supports this capability. 



«lnterface» 
IpUICall 



recordMessageReq (userlnteractionSessionID : in TpSessionID, info : in TpUllnfo, criteria : in 
TpUIMessageCriteria, assignmentID : out TpAssignmentlDRef) : TpResult 

deleteMessageReq (usrInteractionSessionID : in TpSessionID, messagelD : in Tplnt32, assignmentID : out 
TpAssignmentlDRef) : TpResult 

abortActionReq (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID) : TpResult 



Method 
recordMessageReq ( ) 

This asynchronous method allows the recording of a message. The recorded message can be played back at a later time 
with the sendlnfoReqO method. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

info : in TpUIInfo 

Specifies the information to send to the user. This information can be either an ID (for pre-defined announcement or 
text), a text string, or an URL (indicating the information to be sent, e.g. an audio stream). 
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criteria : in TpUIMessageCriteria 

Defines the criteria for recording of messages. 

assignmentID : out TpAssignmentlDRef 

Specifies the ID assigned by the GUI for a User Interaction request. 

Raises 

TpGUISException, TpGeneralException 



Method 
deleteMessageReq ( ) 

This asynchronous method allows to delete a recorded message. 

Parameters 

usrInteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

messagelD : in Tplnt32 

Specifies the message ID. 

assignmentID : out TpAssignmentlDRef 

Specifies the ID assigned by the GUI interface for a User Interaction request. 

Raises 

TpGUISException, TpGeneralException 



Method 

abort Act ionReq ( ) 

This asynchronous method aborts a User Interaction operation, e.g. a sendlnfoReqO, from the specified call leg. The 
call and call leg are otherwise unaffected. The User Interaction call service interrupts the current action on the specified 
leg. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

assignmentID : in TpAssignmentID 

Specifies the User Interaction request to be cancelled. 

Raises 

TpGUISException, TpGeneralException 



8.6 Interface Class IpAppUICall 



Inherits from: IpAppUI. 
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The Call User Interaction Application Interface is implemented by the client application developer and is used to handle 
call User Interaction request responses and reports. 



«lnterface» 
IpAppUICall 



recordMessageRes (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, 
response : in TpUIReport, messagelD : in Tplnt32) : TpResult 

recordMessageErr (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, error : 
in TpUIError) : TpResult 

deleteMessageRes (usrInteractionSessionID : in TpSessionID, response : in TpUIReport, assignmentID : in 
TpAssignmentlDRef) : TpResult 

deleteMessageErr (usrInteractionSessionID : in TpSessionID, error : in TpUIError, assignmentID : in 
TpAssignmentlDRef) : TpResult 

abortActionRes (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID) : TpResult 

abortActionErr (userlnteractionSessionID : in TpSessionID, assignmentID : in TpAssignmentID, error : in 
TpUIError) : TpResult 



Method 
recordMessageRes () 

This method returns whether the message is successfully recorded or not. In case the message is recorded, the ID of the 
message is returned. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the call User Interaction interface for a User Interaction request. 

response : in TpUIReport 

Specifies the type of response received from the device where the message is stored. 

messagelD : in Tplnt32 

Specifies the ID that was assigned to the message by the device where the message is stored. 



Method 
recordMessageErr ( ) 

This method indicates that the request for recording of a message was not successful. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 
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assignmentID : in TpAssignmentID 

Specifies the ID assigned by the call User Interaction interface for a User Interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 



Method 

deleteMessageRes () 

This method returns whether the message is successfully deleted or not. 

Parameters 

usrInteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

response : in TpUIReport 

Specifies the type of response received from the device where the message was stored. 

assignmentID : in TpAssignmentlDRef 

Specifies the ID assigned by the call User Interaction interface for a User Interaction request. 

Raises 

TpGUISException, TpGeneralException 

Method 
deleteMessageErr ( ) 

This method indicates that the request for deleting a message was not successful. 

Parameters 

usrInteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

error : in TpUIError 

Specifies the error which led to the original request failing. 

assignmentID : in TpAssignmentlDRef 

Specifies the ID assigned by the call User Interaction interface for a User Interaction request. 

Raises 

TpGUISException, TpGeneralException 



Method 
abortActionRes () 

This asynchronous method confirms that the request to abort a User Interaction operation on a call leg was successful. 



£75/ 



3GPP TS 29.1 98-5 version 4.0.0 Release 4 34 ETSI TS 1 29 1 98-5 V4.0.0 (2001 -03) 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the call User Interaction interface for a User Interaction request. 

Raises 

TpGUISException, TpGeneralException 



Method 

abort Act ionErr ( ) 

This asynchronous method indicates that the request to abort a User Interaction operation on a call leg resulted in an 
error. 

Parameters 

userlnteractionSessionID : in TpSessionID 

Specifies the User Interaction session ID of the User Interaction. 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the call User Interaction interface for a User Interaction request. 

error : in TpUIError 

Specifies the error which led to the original request failing. 

Raises 

TpGUISException, TpGeneralException 
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9 State Transition Diagrams 

9.1 State Transition Diagrams for I pU I Manager 



"arri\al of user initiated request for user interaction"[ notification acti\« forthis ui 
event ] / create a UI object IpAppUIManager.reportNotification 



createUI / create UI object 
createUICall / create UlCall object 



createNotification 

destroy Notification 
changeNotification 
getNotification 




destroy Notification 



Figure : Application view on the UI Manager 

9.1.1 Active State 

In this state a relation between the Application and a User Interaction SCF (Generic User Interaction or Call User 
Interaction) has been established. The application is now able to request creation of UI and/orUICall objects. 

9.1 .2 Notification Terminatecj State 

When the UI manager is in the Notification terminated state, events requested with createNotification() will not be 
forwarded to the application. There can be multiple reasons for this: for instance it might be that the application receives 
more notifications than defined in the Service Level Agreement. Another example is that the SCS has detected it 
receives no notifications from the network due to e.g. a link failure. In this state no requests for new notifications will 
be accepted. 

9.2 State Transition Diagrams for IpUl 

The state transition diagram shows the application view on the User Interaction object. 
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sendlnfoAndCollectRef 
sendlnbFteq 
IpUIMarager.createUI Active 




sendlnfoAndCcllectReq[ final request 
sendlnfoRe(|[ Snal request 



"request to send message unsuccessfurf final 
request j "sendlnfaErr 

"request to send info and collect resp 
unsuccessful"[ final request ] 
'^endlnfoAndCollectEir 



"requested message has been sent" '^endlnfoRes 
"user input recei\«d" '^sendlnfoAndCollectRes 
"request to send message unsuccessful" '^sendlnfoErr 
"request to send info and collect a response unsuccessful" 

'^endlnfoAndCollectErr 
"fault detected in the user interaction" / 
\ report error on outstanding user interaction 

'\jserlnteract ion Fault Detected ■' Finichpri 1 




lit detected in the user interaction" / report error 
on outstanding user interaction 
'tJserlnteractionFaultDetected 



timeout '^userlnteract ion Fault Detected 



"requested message has been sent"[ final request ] '^endfnfoRes 
"user input recei\fid"[ final request ] '^endtnfoAndCollectRes 



"requested message has been sert"[ not final request ] '^endlnfaRes 
"user input recei\«d"[ not final request ] '^sendlnfoAndCollectRes 
"request to send message unsuccessful"! ^^o* fi'^^l request ] '^endlnfoErr 
"request to send info and collect a response unsuccessful"! no* 'i'^^i' request ] 
'^endlnfoAndCollectErr 



In state Finished a timer mechanism 
should prevent that the object keeps 
occupying resources. In case the timer 
expires, the object should be destroyed 
and userlnteractionFaultDetected should 
be reported to the application. 



Figure : Application view on the Ul object 

9.2.1 Active State 

In this state the UI object is available for requesting messages to be send to the network. 

In case a fault is detected on the User Interaction (e.g. a link failure to the IVR system), userInteractionFaultDetected() 
will be invoked on the application and an error will be reported on all outstanding requests. 

9.2.2 Release Pending State 

A transition to this state is made when the Application has indicated that after a certain message no further messages 
need to be sent to the end-user. There are, however, still a number of messages that are not yet completed. When the last 
message is sent or when the last User Interaction has been obtained, the UI object is destroyed. 

In case the final request failed or the application requested to abort the final request, a transition is made back to the 
Active state. 

In case a fault is detected on the User Interaction (e.g. a link failure to the IVR system), userInteractionFaultDetected() 
will be invoked on the application and an error will be reported on all outstanding requests. 

9.2.3 Finisined State 

In this state the User Interaction has ended. The application can only release the UI object. Note that the application has 
to release the object itself as good OO practice requires that when an object is created on behalf of a certain entity, this 
entity is also responsible for destroying it when the object is no longer needed. 

9.3 State Transition Diagrams for IpUICall 

The state transition diagram shows the application view on the Call User Interaction object. 
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abortAclionReq / cancel he user interaction 



IpUIManager.createUICall 



sendlnfoAndCollectReq[ final request ] 
sendlnfoReq[ final request ] 



al3ortActionReq[ final request is cancelled ] 
/ cancel the user interaction 

"request to send info and collect response 
insuccessful"[ final request ] '^endlnfoAndCollectErr 

"request to send message unsuccessful"! 
final request ] '^sendlnfoErr 



abortActionReq[ not the final request ] / cancel tije 
user interaction 



J ^ 

Active 



release / abort all ongoing user interaction 



"requested message has iDeen sent" '^endhtoRes 
user input received" '^endlnfaAndCollectRes 
"request to send message unsuccessful" '^endlnfoErr 
"request to send info and collect response unsuccessful" 
'SendlnfoAndCollectErr 

\ tpCall.deassignCall 

Vcall terminated" / report error on all outstanding requests "userinteractionFaultDetected 
It detected in the user interaction" / report error on all outstanding requests 
"us e rl nteract i on Fau It Det ected 

Finished "] release 




timeout'XJserlnteractionFaultDetected 



feult detected in frie user'iritetaction" / report error on outstanding requests 
'\jser In teractionFau It Detected 
/call terminated" / report error on all outstanding requests "userlnteractionFault Detected 
IpCall.deassignCall 



release / abort all ongoing user interaction 



"user input recei\«d"[ final request ] '^endlnfoAndCollectReq 
'requested message,has been sent"[ final request ] "sendlnfoRes 



"user input received"! '^o^ 'ri^l request ] '^endlnfoAndCollectRes 
"requested message has been sent"[ not final request ] 'BendlnfoRes 
"request to send info and collect a response unsuccessful "[ not final request] 
"SendlnfoAndCollectErr 

"request to send message unsuccessful"! not final request ] "sendlnfoErr 



Iready requested announcements 1^ 
ill continue, even when 
pplication releases the object 



h state Finished a timer mechanism 
I should pre\«nt that the object keeps 

occupying resources. In case the timer 
I expires, the object should be destroyed 

and userlnteractionFaultDetected should 

be reported to the application. 



Figure : Application view on the UlCall object 

9.3.1 Active State 

In this state a UlCall object is available for announcements to be played to an end-user or obtaining information from 
the end-user. 

When the application de-assigns the related Call object, a transition is made to the Finished state. However, all 
requested announcements will continue, even when the application releases the UlCall object. 

When the related call is due to some reason terminated, a transition is made to the Finished state, the operation 
userlnteractionFaultDetectedO will be invoked on the application and an error will be reported on all outstanding 
requests. 

In case a fault is detected on the User Interaction (e.g. a link failure to the IVR system), userlnteractionFaultDetectedO 
will be invoked on the application and an error will be reported on all outstanding requests. 



9.3.2 Release Pending State 



A transition to this state is made when the Application has indicated that after a certain announcement no further 
announcements need to be played to the end-user. There are, however, still a number of announcements that are not yet 
completed. When the last announcement is played or when the last User Interaction has been obtained, the UlCall 
object is destroyed. In case the final request failed or the application requested to abort the final request, a transition is 
made back to the Active state. 

When the application de-assigns the related Call object, a transition is made to the Finished state. However, all 
requested announcements will continue, even when the application releases the UlCall object. 

When the related call is due to some reason terminated, a transition is made to the Finished state, the operation 
userlnteractionFaultDetectedO will be invoked on the application and an error will be reported on all outstanding 
requests. 

In case a fault is detected on the User Interaction (e.g. a link failure to the IVR system), userlnteractionFaultDetectedO 
will be invoked on the application and an error will be reported on all outstanding requests. 
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9.3.3 Finished State 

In this state the User Interaction has ended. The application can only release the UlCall object. Note that the application 
has to release the object itself as good OO practice requires that when an object is created on behalf of a certain entity, 
this entity is also responsible for destroying it when the object is no longer needed. 



10 Service Properties 

10.1 User Interaction Service Properties 

The following table lists properties relevant for the User Interaction API. 



Property 


Type 


Description 


P_INFO_TYPE 


INTEGER_SET 


Specifies wlietlier the UI SCS supports text or URLs etc. Allowed value set: 

{P_INFO_ID, 

P_URL, 

P_TEXT) 



The previous table lists properties related to capabilities of the SCS itself The following table lists properties that are 
used in the context of the Service Level Agreement, e.g. to restrict the access of applications to the capabilities of the 
SCS. 



Property 



Type 



Description 



P_TRIGGERING_ADDRESSES 
P_SERVICE_CODE 



ADDRESS_RANGE_SET Specifies which numbers the notification may be set 

iNTEGER_SET Specifies the service codes that may be used for notification requests. 



1 1 Data Definitions 
11.1 TpUIFault 



Defines the cause of the UI fault detected. 



^H Name 


Value 




P_UI_FAULT_UNDEFINED 





Undefined 


P_UI_CALL_ENDED 


1 


The related Call object has been terminated. Therefore, the UlCall object is also terminated. No 
further interaction is possible with this object. 



11.2 IpUl 

Defines the address of an ipUl Interface. 

11.3 IpUIRef 

Defines a Reference to type IpUI. 

11.4 IpUIRefRef 

Defines a Reference to type IpUIRef. 
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11.5 IpAppUl 

Defines the address of an ipAppUl Interface. 

11.6 IpAppUIRef 

Defines a Reference to type IpAppUl. 

11.7 IpAppUIRefRef 

Defines a Reference to type IpAppUIRef . 

11.8 IpAppUl Manager 

Defines the address of an IpAppUIManager Interface. 

1 1 .9 IpAppUIManagerRef 

Defines a Reference to type IpAppUIManager . 



11.10 TpUICallldentifier 



Defines the Sequence of Data Elements that unambiguously specify the UlCall object. 



Structure Element Name 


Structure Element Type 


Structure Element Description ■■ 


UICallRef 


IpUICallRef 


This element specifies the interface reference for the UlCall object. 


UserlnteractionSessionID 


TpSessionID 


This element specifies the User Interaction session ID. 



11.11 TpUICallldentifierRef 

Defines a reference to type TpUICallldentifier. 

11.12 TpUICollectCriteria 

Defines the Sequence of Data Elements that specify the additional properties for the collection of information, 
such as the end character, first character timeout, inter-character timeout, and maximum interaction time. 



Structure Element Name 


Structure Element Type 


MinLength 


Tplnt32 


MaxLength 


Tplnt32 


EndSequence 


TpString 


StartTimeout 


TpDuration 


Inter Char Timeout 


TpDuration 



The structure elements specify the following criteria: 

MinLength : Defines the minimum number of characters (e.g. digits) to collect. 

MaxLength : Defines the maxmum number of characters (e.g. digits) to collect. 

EndSequence : Defines the character or characters which terminate an input of variable length, e.g. 

phonenumbers. 
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StartTimeout : specifies the value for the first character time-out timer. The timer is started when the 

announcement has been completed or has been interrupted. The user should enter the start 
of the response (e.g. first digit) before the timer expires. If the start of the response is not 
entered before the timer expires, the input is regarded to be erroneous. After receipt of the 
start of the response, which may be valid or invalid, the timer is stopped. 

InterCharTimeOut : specifies the value for the inter-character time-out timer. The timer is started when a 

response (e.g. digit) is received, and is reset and restarted when a subsequent response is 
received. The responses may be valid or invalid, the announcement has been completed or 
has been interrupted. 

Input is considered successful if the following applies: 
If the EndSequence is not present (i.e. NULL): 

when the InterCharTimeOut timer expires; or 

when the number of valid digits received equals the MaxLength. 
If the EndSequence is present: 

when the InterCharTimeOut timer expires; or 

when the EndSequence is received; or 

when the number of valid digits received equals the MaxLength. 

In the case the number of valid characters received is less than the MinLength when the InterCharTimeOut timer 
expires or when the EndSequence is received, the input is considered erroneous. 

The collected characters (including the EndSequence) are sent to the client application when input has been 
successful. 



11.13 TpUIError 



Defines the UI error codes. 



Name 


Value 


Description ^| 


P_UI_ERROR_UNDEFINED 





Undefined error 


P_UI_ERROR_ILLEGAL_INFO 


1 


The specified information (Infold, InfoData, or InfoAddress) is invalid 


P_UI_ERROR_ID_NOT_FOUND 


2 


A legal Infold is not known to the the User Interaction service 


P_UI_ERROR_RESOURCE_UNAVAILABLE 


3 


The information resources used by the User Interaction service are unavailable, e.g. 
due to an overload situation. 


P_UI_ERROR_ILLEGAL_RANGE 


4 


The values for minimum and maximum collection length are out of range 


P_UI_ERROR_IMPROPER_USER_RESPONSE 


5 


Improper user response 


P_UI_ERROR_ABANDON 


6 


The specified leg is disconnected before the send information completed 


P_UI_ERROR_NO„OPERATION_ACTIVE 


7 


There is no active User Interaction for the specified leg. Either the apphcation did not 
start any User Interaction or the User Interaction was already finished when the 

abortAction_Req ( ) was called. 


P_UI_ERROR_NO_SPACE_AVAILABLE 


8 


There is no more storage capacity to record the message when the 
recordMessage ( ) operation was called 


P_UI_ERROR RESOURCE TIMEOUT 


9 


The request has been accepted by the resource but it did not report a result. 



The call User Interaction object will be automatically de-assigned if the error P_UI_ERROR_ABANDON is reported, as a 
corresponding call or call leg object no longer exists. 



11.14 TpUIEventCriteria 



Defines the Sequence of Data Elements that specify the additional criteria for receiving a UI notification 
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Structure Element 
Name 


Structure Element 
Type 


HHHj^^^g ^^^^^^^^^■Bil 


OriginatingAddress 


TpAddressRange 


Defines the originating address for whicli tlie notification is requested. 


DestinationAddress 


TpAddressRange 


Defines the destination address or address range for which the notification is requested. 


ServiceCode 


TpString 


Defines a 2-digit code indicating the UI to be triggered. The value is operator specific. 



11.15 TpUIEventCriteriaResultSetRef 

Defines a reference to TpUIEventCriteriaResultSet. 

11.16 TPUIEventCriteriaResultSet 

Defines a set of TpUIEventCriteriaResult. 

11.17 TPUIEventCriteriaResult 

Defines a sequence of data elements that specify a requested event notification criteria with the associated 
assignmentlD. 



Structure Element Name 


Structure Element Type 


Structure Element Description || 


EventCriteria 


TpUIEventCriteria 


The event criteria that were specified by the application. 


AssignmentlD 


Tplnt32 


The associated assignmentlD. This can be used to disable the notification. 



11.18 TpUIEventlnfo 



Defines the Sequence of Data Elements that specify a UI notification 



Structure Element 
Name 


Structure Element m 
Type ^1 


11^^^^^^^^^^^ Structure Element^^^^^^^^^^Hlj 


OriginatingAddress 


TpAddress 


Defines the originating address. 


DestinationAddress 


TpAddress 


Defines the destination address. 


ServiceCode 


TpString 


Defines a 2-digit code indicating the UI to be triggered. 
The value is operator specific. 


DataType Indication 


TpUIEventlnfoDataType 


Identifies the type of contents in the dataString. 


DataString 


TpString 


Freely defined data string with a limited length e.g. 160 bytes according to the 
network policy. 



11.19 TpUIEventlnfoDataType 

Defines the type of the dataString parameter in the method userlnteractionEventNotify. 



Name 


Value 


Description 


P_UI_EVENT_DATA_TYPE_UNDEFINED 





Undefined (e.g. binary data) 


P_UI_EVENT_DATA_TYPE_UNSPECIFIED 


1 


Unspecified data 


P_UI_EVENT_DATA_TYPE_TEXT 


2 


Text 


P_UI_EVENT_DATA_TYPE_USSD_DATA 


3 


USSD data starting with coding scheme 



11.20 TpUlldentifier 

Defines the Sequence of Data Elements that unambiguously specify the UI object 
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Structure Element Name 


Structure Element Type 


Structure Element Description j 


UIRef 


IpUIRef 


This element specifies the interface reference for the UI object. 


UserlnteractionSessionID 


TpSessionID 


This element specifies the User Interaction session ID. 



11.21 TpUlldentifierRef 

Defines a reference to type TpUIIdentifier. 

11.22 TpUllnfo 

Defines the Tagged Choice of Data Elements that specify the information to send to the user. 





Tag Element Type 




1 


TpUIInfoType 





Tag Element Value 


Choice Element Type 


Choice Element Name 


P_UI_INFO_ID 


Tplnt32 


Infold 


P_UI_INFO_DATA 


TpString 


Inf oData 


P_UI_INFO_ADDRESS 


TpURL 


Inf oAddress 



The choice elements represents the following 

InfoID: 



Inf oData : 



Inf oAddress : 



defines the ID of the user information script or stream to send to an end-user. The values of 
this data type are operator specific. 

defines the data to be sent to an end-user's terminal. The data is free-format and the 
encoding is depending on the resources being used.. 

defines the URL of the text or stream to be sent to an end-user's terminal. 



11.23 TpUIInfoType 

Defines the type of the information to be send to the user. 



Name 


Value 


Description 


P_UI_INFO_ID 


1 


The information to be send to an end-user consists of an ID 


P_UI_INFO_DATA 


2 


The information to be send to an end-user consists of a data string 


P„UI_INFO_ADDRESS 


3 


The information to be send to an end-user consists of a URL. 



11.24 TpUIMessageCriteria 



Defines the Sequence of Data Elements that specify the additional properties for the recording of a message. 



Structure Element Name 


Structure Element Type 


EndSequence 


TpString 


MaxMes sage Time 


TpDuration 


MaxMessageSize 


Tplnt32 



The structure elements specify the following criteria: 

EndSequence : Defines the character or characters which terminate an input of variable length, e.j 

phonenumbers. 

MaxMessageTime : specifies the maximum duration in seconds of the message that is to be recorded. 
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MaxMessageSize : 



If this parameter is non-zero, it specifies the maximum size in bytes of the message that is 
to be recorded. 



11.25 TpUIReport 

Defines the UI reports if a response was requested. 



Name jg^g^ 


Value 


^^^^^^^^^^ ^^^^^^^^^^^ 


P_UI_REPORT_UNDEFINED 





Undefined report 


P_UI_REPORT_INFO_SENT 


1 


Confirmation tliat the information has been sent 


P_UI_REPORT_INFO_COLLECTED 


2 


Information collected., meeting the specified criteria. 


P_UI_REPORT_NO_INPUT 


3 


No information collected. The user immediately entered the delimiter character. 
No valid information has been returned 


P_UI_REPORT_TIMEOUT 


4 


No information collected. The user did not input any response before the input timeout 

expired 


P_UI_REPORT_MESSAGE_STORED 


5 


A message has been stored successfully 


P_UI_REPORT_MESSAGE_NOT_STORED 


6 


The message has not been stored successfully 


P_UI_REPORT_MESSAGE_DELETED 


7 


A message has been deleted successfully 


P_UI_REPORT_MESSAGE_NOT_DELETED 


8 


A message has not been deleted successfully 



11.26 TpUIResponseRequest 

Defines the situations for which a response is expected following the User Interaction. 



Name 


Value 


Description l 


P_UI_RESPONSE_REQUIRED 


1 


The User Interaction Call shall send a response when the request has completed. 


P_UI_LAST_ANNOUNCEMENT_IN_A_ROW 


2 


This is the final announcement within a sequence. It might, however, be that 
additional announcements will be requested at a later moment. The User Interaction 
Call service may release any used resources in the network. The UI object will not be 

released. 


P_UI_FINAL_REQUEST 


4 


This is the final request. The UI object will be released after the information has been 
presented to the user. 



This parameter represent a so-called bitmask, i.e. the values can be added to derived the final meaning. 

1 1 .27 TpU ITargetObjectType 

Defines the type of object where User Interaction should be performed upon. 



Name ^^^^^^ 


Value 


Description ^hi 


P_UI_TARGET_OBJECT_CALL 





User-interaction will be performed on a complete Call. 


P_ULTARGET_OBJECT_MULTI_PARTY_CALL 


1 


User-interaction will be performed on a complete Multi-party Call. 


P_UI_TARGET_^OBJECT^CALL_LEG 


2 


User-interaction will be performed on a single Call Leg. 



11.28 TpUITargetObject 



Defines the Tagged Choice of Data Elements that specify the object to perform User Interaction on. 





Tag Element Type 






TpUITargetObject Type 
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Tag Element Value ma^^ 


Choice Element Type 


Choice Element Name 


P_UI_TARGET_OBJECT_CALL 


TpCall Identifier 


Call 


P_UI_TARGET_OBJECT_MULTI_PARTY„CALL 


TpMultiPartyCall Identifier 


MultiPartyCall 


P_UI_TARGET_OBJECT_CALL_LEG 


TpCallLeg Identifier 


CallLeg 



11.29 TpUIVariablelnfo 



Defines the Tagged Choice of Data Elements that specify the variable parts in the information to send to the 
user. 





Tag Element Type 






TpUIVariablePartType 





Tag Element Value 


Choice Element Type 


Choice Element Name 


P_UI„VARIABLE_PART_INT 


Tplnt32 


VariableP art Integer 


P_UI_VARIABLE_PART_ADDRESS 


TpString 


VariablePart Address 


P_UI_VARIABLE_PART_TIME 


TpTime 


VariablePartTime 


P_UI_VARIABLE_PART„DATE 


TpDate 


VariableP art Date 


P^UI_VARIABLE„PART„PRICE 


TpPrice 


VariablePartPrice 



11.30 TpUIVariablelnfoSet 

Defines a Numbereci Set of Data Elements of TpUIVariablelnfo. 



1 1 .31 TpUIVariablePartType 

Defines the type of the variable parts in the information to send to the user. 



Name 


Value 


^^~ DescriptioW^^^^HI 


P_UI_VARIABLE_PART_INT 





Variable part is of type integer 


P_UI_VARIABLE_PART_ADDRESS 


1 


Variable part is of type address 


P_UI_VARIABLE_PART_TIME 


2 


Variable part is of type time 


P_UI_VARIABLE_PART_DATE 


3 


Variable part is of type date 


P_UI_VARIABLE_PART_PRICE 


4 


Variable part is of type price 
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Annex A (normative): 

OMG IDL Description of User Interaction SCF 

The OMG IDL representation of this interface specification is contained in a text file (ui.idl contained in archive 
2919805IDL.ZIP) which accompanies the present document. 
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Annex B (informative): 

Differences between this draft and 3GPP TS 29.198 R99 

B.1 Interface IpUIIVIanager 

create enableUI Notification ( applnterface appUIManager : in IpAppUIManagerRef, eventCriteria : in 
TpUIEventCriteria, assignmentID : out TpAssignmentlDRef) : TpResult 

createUICall (appUI : in IpAppUICallRef, uiTargetObject : in TpUITargetObject , callldentifier : in cc::TpCallIdentifier, 
callLegldentifier : in cc::TpCallLegIdentifier, userlnteraction : out TpUICallldentifierRef) : TpResult 

destroy disableUI Notification (assignmentID : in TpAssignmentID) : TpResult 

changeNotification (assignmentID : in TpAssignmentID, eventCriteria : in TpUIEventCriteria) : TpResult 

getNotification (eventCriteria : out TpCallEventCriteriaResultSetRef) : TpResult 

B.2 Interface IpAppUIManager 

UserlnteractionEventNotify reportNotification (ui userlnteraction : in TpUIIdentifier , eventlnfo : in TpUIEventlnfo , 
assignmentID : in TpAssignmentID , applnterface appUI : out IpAppUIRefRef ) : TpResult 



B.3 Interface IpUl 



sendlnfoReq (userlnteractionSessionID : in TpSessionID, info : in TpUIInfo, language : in TpLanguage , variablelnfo : 
in TpUIVariablelnfoSet, repeatlndicator : in Tplnt32, responseRequested : in TpUIResponseRequest, assignmentID : 
out TpAssignmentlDRef) : TpResult 

sendlnfoReq (userlnteractionSessionID : in TpSessionID, info : in TpUIInfo, language : in TpLanguage, variablelnfo ; 
in TpUIVariablelnfoSet, repeatlndicator : in Tplnt32, responseRequested : in TpUIResponseRequest, assignmentID : 
out TpAssignmentlDRef) : TpResult 



B.4 Interface IpAppUl 



sendInfoAndCollectRes(userInteractionSessionID : in TpSessionID , assignmentID : in TpAssignmentID, response : in 
TpUIReport , iflfe collectedlnfo : in TpString) : TpResult 

B.5 Interface IpUICall 

The following method was added: 

deleteMessageReq(userInteractionSessionID : in TpSessionID , messagelD : in Tplnt32 , assignmentID : out 
TpAssignmentlDRef) : TpResult 

B.6 Interface IpAppUICall 

The following methods were added: 

deleteMessageRes(userInteractionSessionID : in TpSessionID . response : in TpUIReport . assignmentID : in 
TpAssignmentID) : TpResult 

deleteMessageErr(userInteractionSessionID : in TpSessionID , error : in TpUIError , assignmentID : in 
TpAssignmentID) : TpResult 
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B.7 Type TpU I Report 

TpUIReport 

Defines the UI eaH-reports if a response was requested. 
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^^^^^1 Name 


Value 


^^^^^^^^P ^^^^^^^^^^^Hl 


P_UI_REPORT_UNDEFINED 





Undefined report 


P_UI_REPORT_ANNOUNCEMENT_ENDED 
P UI REPORT INFO SENT 


1 


Confirmation that the announcement information has endedbeen sent 


P_UI_REPORT_LECAL_INPUT 

P UI REPORT INFO COLLECTED 


2 


Information collected., meeting the specified criteria. 


P_UI_REPORT_NO_INPUT 


3 


No information collected. The user immediately entered the delimiter character. 
No valid information has been returned 


P_UI_REPORT_TIMEOUT 


4 


No information collected. The user did not input any response before the input 
timeout expired 


P_UI_REPORT_MESSAGE_STORED 


5 


A message has been stored successfully 


P_UI_REPORT_MESSAGE_NOT_STORED 


6 


The message has not been stored successfully 


P UI REPORT MESSAGE DELETED 


7 


A message has been deleted successfully 


P UI REPORT MESSAGE NOT DELETED 


8 


A message has not been deleted successfully 



B.8 TypeTpUIError 

TpUIError 

Defines the UI eaH-error codes. 



^^^^^^^^^H Name ^^^^^^^^^fl 


"Value '1 


^^^^^^^^^VDescription ~^^^^^^^^H 


P_UI_ERROR_UNDEFINED 





Undefined error 


P_UI_ERROR_ILLEGAL_iBINFO 


1 


The specified information id(InfoId, InfoData, or 
InfoAddress) specified is invalid 


P_UI_ERROR_ID_NOT_FOUND 


2 


A legal information idlnfold is not known to the User 
Interaction service 


P_UI_ERROR_RESOURCE_UNAVAILABLE 


3 


The information resources used by the User Interaction 
service are unavailable, e.g. due to an overload situation. 


P_UI_ERROR_ILLEGAL_RANGE 


4 


The values for minimum and maximum collection length 
are out of range 


P_UI_ERROR_IMPROPER_CALLER_USER_RESPONSE 


5 


Improper user response 


P_UI_ERROR_ABANDON 


6 


The specified leg is disconnected before the send 
information completed 


P_UI_ERROR_NO_OPERATION_ACTIVE 


7 


There is no active User Interaction for the specified leg. 

Either the apphcation did not start any User Interaction or 

the User Interaction was already finished when the 

abortAction_Req was called. 


P„UI„ERROR_NO_SPACE_AVAILABLE 


8 


There is no more storage capacity to record the message 
when the recordMessage ( ) operation was called 


P_UI_ERROR RESOURCE TIMEOUT 


9 


The request has been accepted by the resource but it did 
not report a result. 



B.9 Type TpUIEventCriteriaResult 

TpUIEventCriteriaResultSetRef 
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Defines a reference to TpUIEventCriteriaResultSet 

TPUIEventCriteriaResultSet 

Defines a set of TpUIEventCriteriaResult 



TPUIEventCriteriaResult 

Defines a sequence of data elements that specify a requested event notification criteria with the associated 
assignmentlD. 



1 structure Element 
1 Name 


Structure Element 
Type 


Structure Element Description 


Event Criteria 


TpUIEvent Criteria 


The event criteria that were 
specified by the application. 


AssianmentID 


Tplnt32 


The associated assianmentID . This 
can be used to disable the 
notification . 



B.1 TpUITargetObjectType 

TpUITargetObjectType 

Defines the type of object where User Interaction should be performed upon. 





Val^^J^^^' Description II 


P_UI_TARGET_^OBJECT_CALL 





User-interaction will be performed on a 
complete Call. 


P_UI_TARGET_OBJECT_MULTI_PARTY_CALL 


1 


User-interaction will be performed on a 
complete Multi-party Call. 


P„UI_TARGET_OBJECT_CALL_LEG 


2 


User-interaction will be performed on a single 
Call Leg. 



TpUITargetObject 

Defines the Tagged Choice of Data Elements that specify the object to perform User Interaction on. 





^^P Tag Element Type ^11 






TpUITargetObjectType 





^^mmniiimii^^g 


UliiiiiiUi^y^lJiiiij^^ 


P_UI_TARGET_OBJECT_CALL 


TpCallldentifier 


Call 


P_UI_TARGET_OBJECT_MULTI_PARTY_CALL 


TpMultiPartyCall Identifier 


MultiPartyCall 


P_UI_TARGET_OBJECT_CALL_LEG 


TpCallLegldentifier 


CallLeg 
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B.11 TpUIVariablelnfo 

TpUIVariablelnfo 

Defines the Tagged Choice of Data Elements that specify the variable parts in the information to send to the 
user. 





^^■" Tag Element Type '^■' 






TpUIVariablePartTvpe 





Tag Element Value ^^^^^" 


"^ Choice Element Type 


Choice Element Pfame^l 


P^ULVARIABLE_PART_INT 


Tplnt32 


VariableP art Integer 


P_UI_VARIABLE_PART_ADDRESS 


TpString 


VariablePart Address 


P_UI_VARIABLE_PART_TIME 


TpTime 


VariablePartTime 


P_UI_VARIABLE_PART_DATE 


TpDate 


VariablePartDate 


P_UI_VARIABLEJART_PRICE 


TpPrice 


VariablePartPrice 
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Annex C (informative): 
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